% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ejscreenit.R
\name{ejscreenit}
\alias{ejscreenit}
\title{Get EJScreen results near each site, compiled as a table, with map and plot}
\usage{
ejscreenit(
  x,
  y = NULL,
  radius = 3,
  maxradiusmiles = 10,
  fips = NULL,
  shapefile = NULL,
  namestr = "",
  nosave = TRUE,
  nosee = TRUE,
  save_map = TRUE,
  see_map = TRUE,
  save_plot = TRUE,
  see_plot = TRUE,
  save_table = TRUE,
  see_table = FALSE,
  interactiveprompt = FALSE,
  calculate_ratios = TRUE,
  nicenames = TRUE,
  folder = ".",
  getstatefromplacename = TRUE,
  ...
)
}
\arguments{
\item{x}{Point locations may be specified in several ways:
\itemize{
\item x can be a vector of longitudes (decimal degrees),
in which case y also must be provided as latitudes; or
\item x can be the path/filename to a file in .xlsx or .csv format with lat, lon header names
\item x can be a data.frame, data.table, or matrix (or list) with lat,lon as column names (or names of list elements)
\item x can be omitted if one is using RStudio interactively, in which case the user is
prompted to select a file from a local drive.
}}

\item{y}{latitudes, or ignored if x was a file or table with lat,lon info.}

\item{radius}{in miles - gets data on all residents within that distance from each point}

\item{maxradiusmiles}{optional in case you want to use a radius of more than default cap}

\item{fips}{if used instead of x,y it can specify fips codes of counties, tracts, or blockgroups}

\item{shapefile}{not implemented}

\item{namestr}{optional text}

\item{nosave}{logical, if TRUE, sets as FALSE and overrides save_map, save_plot, save_table. Ignored if FALSE.}

\item{nosee}{logical, if TRUE, sets as FALSE and overrides see_map, see_plot, see_table. Ignored if FALSE.}

\item{save_map}{logical, whether to save png image file locally}

\item{see_map}{logical, whether to display interactive map}

\item{save_plot}{logical, whether to save png image file locally}

\item{see_plot}{logical, whether to display plot (boxplots)}

\item{save_table}{logical, whether to save table of data in a file locally}

\item{see_table}{logical, whether to display interactive table}

\item{interactiveprompt}{logical, whether to prompt for upload of file and ask to hit key to continue after map shown, etc.
If interactive() is TRUE, this actually defaults to TRUE.}

\item{calculate_ratios}{whether to add columns with ratio of raw score to the US or State average}

\item{nicenames}{whether to use long plain english headers in table or R variable names,
e.g.,  "Particulate Matter (PM 2.5 in ug/m3)" not "pm"}

\item{folder}{full path of directory in which to save files like map, plot, table
Default is working directory.}

\item{getstatefromplacename}{set to FALSE if you need the exact output of API and
TRUE if you want to try to extract ST abbrev and statename from the placename field,
which is more likely to be correct than the stateAbbr and stateName fields in the API output.}

\item{...}{passed to \code{\link[=ejscreenapi_plus]{ejscreenapi_plus()}}}
}
\value{
Returns a list with map, boxplot, table
\itemize{
\item map of sites with popups of EJ stats, as returned plot,
viewed interactive map and .png
\item graphic boxplot of some demographics as ratios to average, as returned plot,
viewed noninteractive plot and .png
\item table of results as a returned data.frame,
viewed interactive datatable, and .xlsx and .csv
Which includes us.ratios and state.ratios via one row per site
and one column per indicator as ratios to US and to State average.

It also now drops redundant columns where the same numbers had been returned from API
using the normal name and a synonym name.
}
}
\description{
This is the main high-level function that does all the work involved in
using the EJScreen API outside of the web app to get results for
multiple locations compiled in one table.
}
\details{
This function provides EJScreen indicator results near each of a list of sites,
all in one function, for those who want to do so in RStudio (for interactive analysis)
or via their own software/apps (programmatically)
rather than through the web app interface. It is an alternative to EJAM, as
explained below.

Based on a set of places, \code{ejscreenit()} requests an EJScreen standard report for each place
and assembles all those results as a single spreadsheet. The indicators include
demographic and environmental indicators as well as EJ Indexes that combine them,
and some geospatial information about each site.

\code{ejscreenit()} is the basic, high-level tool that enables easy access to the EJScreen API
for a list of sites, outside the context of a web app. It accepts lat/lon values
flexibly and interactively in the R console,
and then uses the helper functions below to return a list of 3 objects:
\itemize{
\item a table
\item an interactive map (html widget with popups in R console or saved as html file)
\item plot of some indicators over the range of sites
}

The table it provides uses plain-English column headers, such as
"Traffic Proximity and Volume (daily traffic count/distance to road)"
}
\section{EJAM vs EJScreen}{
To obtain \emph{overall summary} statistics (and faster results) use ejamit()
from the EJAM package instead of ejscreenit().
The two tools, ejamit() and ejscreenit(), are different, and have pros and cons:

The key advantages of EJAM are
\enumerate{
\item \emph{ejscreenit / EJScreen API is much, much slower than EJAM}
\item \emph{ejscreenit cannot provide an overall summary across sites, while EJAM can}
}

An "overall summary" here means, for example, the overall percent low income
among all unique residents near any one or more of the sites.
This inability to provide an overall summary aggregating across sites
is due to limitations of the EJScreen API
-- it does not provide all data needed to correctly aggregate across sites
(see detailed explanation in the ejscreenapi About document).
}

\section{Inputs and Outputs}{
The ejscreenit() function accepts a set of points (locations) and a radius, and then
accesses EJScreen (the server via API) to assemble a list of results
similar to the EJScreen standard report but for each of many sites.

Points can be specified in several ways:
\itemize{
\item as a table (columns lat, lon that are the geographic coordinates)
\item in a spreadsheet file with that info (named, or pointed to interactively in RStudio)
}

The function returns a list of items: table, map, plot
\itemize{
\item a table of scores that are like the EJScreen standard buffer report, but with one row per site (input point)
\itemize{
\item and as a set of columns in that table, a set of ratios, which are the
indicator value nearby a site divided by the indicator value in the US overall
(which puts all indicators in common units, facilitating comparisons,
offering a summary statistic that is complementary to the percentile but may be more useful in some cases)
}
\item a map with interactivity and popups of results at each point
\item a plot/graphic visualization of the range of sites
}
}

\section{Details of helper functions used}{
This function works by requesting each site report from EPA servers
via the \href{https://ejscreen.epa.gov/mapper/ejscreenapi1.html}{EJScreen API}
using various helper functions.
It uses functions including the following:
\itemize{
\item \code{\link[=ejscreenit]{ejscreenit()}} is the basic, high-level tool that enables access to the EJScreen API
for a list of sites, outside the context of a web app. It accepts lat/lon values flexibly and interactively in the R console,
and then uses the helper functions below to return a list of 3 objects: a table, interactive map, and plot.
The table it provides uses plain-English column headers, such as
"Traffic Proximity and Volume (daily traffic count/distance to road)"
\itemize{
\item \code{\link[=ejscreenapi_plus]{ejscreenapi_plus()}} can accept a file of point data, uses \code{\link[=ejscreenapi]{ejscreenapi()}} to get EJScreen stats,
and then prepends input table and renames columns as R variables like "traffic.score"
\itemize{
\item \code{\link[=ejscreenapi]{ejscreenapi()}}  gets EJ stats for many points as a data.table of many rows.
\item \code{\link[=ejscreenapi1]{ejscreenapi1()}} gets EJ stats for 1 point via API, as data.frame of 1 row.
\item \code{\link[=ejscreenRESTbroker]{ejscreenRESTbroker()}} gets EJ stats for one point as JSON.
}
}
}

Also used are
\code{\link[=ejscreenapi_plus]{ejscreenapi_plus()}}, \code{\link[=ejscreenapi]{ejscreenapi()}}, \code{\link[=urls_clusters_and_sort_cols]{urls_clusters_and_sort_cols()}},
\code{\link[=fixcolnames]{fixcolnames()}}, \code{\link[=url_linkify]{url_linkify()}}, \code{\link[=popup_from_ejscreen]{popup_from_ejscreen()}}, \code{\link[=calc_ratios_to_avg]{calc_ratios_to_avg()}}, \code{\link[=boxplots_ratios]{boxplots_ratios()}}
}

\examples{
\dontrun{
 pts <- testpoints_50[1:3, ] # sample data from package
 mapfast(pts)
 #pts <- system.file("testdata/latlon/testpoints_10.xlsx", package="EJAM") 
 if (interactive)
 
 x <- ejscreenit(pts, 
   save_map = F, save_plot = F, save_table = F, folder = "~", see_table = T)
 
 myradius <- 1 # in miles
 # myradius <- 5000 / meters_per_mile # 5 kilometer radius, approx 3.1 miles
 # Get results from server by using API 
 x <- ejscreenit(
   pts=pts, radius = myradius,
   save_table = FALSE, save_map = FALSE, save_plot = FALSE)
  
 # see format of output results
 names(x) # [1] "table" "map"   "plot"
 
 y = ejscreenapi_plus(pts, radius = myradius)
 all.equal(x$table, y)
 
 # For this table view, remove map and pdf URL columns 
 y <- x$table[ , !grepl("EJScreen", names(x$table))] 
 t(y[1, ])  # see one column of results
 DT::datatable(y)  # see interactive data table view in viewer of RStudio
 
 # View links in RStudio Viewer window rather than shiny app or Excel 
 html_print(HTML(paste(paste(x$table[,"EJScreen Report"], collapse="<br>"),
    "<p></p>", paste(x$table[,"EJScreenMAP"], collapse="<br>") )  ))
 
 # View the boxplots of results
 x$plot
 
 # Save the plot as a file:
 
 # You can save it while running ejscreenit()
 # by including the parameters save_map = T, nosave = F, folder = "."
 # or afterwords like this:
 
 png(filename = file.path(folder,"Boxplot of EJ stats.png"), 
   width = 1200, height = 600)
 x$plot
 dev.off()
 
 # Save the map as a file:
 
 # You can save the map while running ejscreenit()
 # by including the parameters save_plot = T, nosave = F, folder = "."
 # or afterwords save as an interactive HTML webpage, like this:
 
 # htmltools::save_html(x$map, "mapfile.html")
 
 # or make it printable as a static file like this:
 x$map \%>\% leaflet.extras2::easyprintMap(
   filename = file.path(folder, "map.png"), exportOnly = TRUE)
}

}
\seealso{
\code{\link[=ejscreenapi_plus]{ejscreenapi_plus()}}
}
